<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>Metrics 1.3.6</title>
</head>

<body>

<a name="gettingstarted"/>
<h1> <a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=70202&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" /></a>
	Metrics 1.3.6 - Getting started</h1>
<h2><strong>Note: This version requires <a href="http://www.eclipse.org/downloads">Eclipse 3.1</a> </strong>	</h2>
To access the sourceforge project page click <a href="http://www.sourceforge.net/projects/metrics">here</a>.</h2>
<P/>
What's new:<br>
<UL>
	<LI>Updated to work with eclipse 3.1</LI>
	<LI>Bug in VG computation fixed</LI>
	<LI>Bug in lines of code computation fixed</LI>
	<LI>Bug in CE Computation fixed</LI>
	<LI>Bug in I Computation fixed</LI>
	<LI>Batch execution fixed</LI>
	<LI>Several other minor bugfixes</LI>
</UL>

I want to thank Guillaume Boissier for doing most of the work on this release. Thanks!
I also want to thank Uwe Kubosch for contributing the layered package view. Thanks!

<h2>Installation procedure</h2>
Run Eclipse, go to Help menu -&gt; Software Updates -&gt; Find and Install ... 
On the opening dialog choose Search for new features to install.
Add a new Remote site with the following url 
<B>http://metrics.sourceforge.net/update</B> and follow the instructions for installation.
<P/>

To use the metrics plugin you have to be in a Java or Java Browsing perspective or any other perspective that shows java resources as source folders,
packages and compilation units. The simple resource perspective won't do. This makes sense since the metrics are all about counting aspects of your 
java code.<p/>

To start using the Metrics View, use Windows -&gt; Show View -&gt; Other and navigate to the Metrics View, as shown in the next image.<P/>

<center>
	<img src="showview.gif"/>
</center>

Initially the resulting view will show a brief usage message because no metrics have been calculated yet.
To start collecting metrics for a project, right click on the project and from the popup menu select
"Metrics-&gt;Enable" (or alternatively, use the properties page ).This will tell Eclipse to calculate metrics 
every time a compile happens. Now that you've enabled a project, the easiest way to calculate all its metrics is 
to do a full rebuild of that project. The metrics view will indicate the progress of the metrics calculations as they are 
being performed in the background. When it's all done, the metrics view will look something like this:<P/>

<center>
	<img src="view.gif"/>
</center>

Note that any metric shown in blue can be double-clicked to navigate to the resource causing the maximum value
for the metric. Since 1.2.0, the metrics table is actualy a table tree, allowing you
to expand each metric to show the values at levels below the selected resource.
The child elements at each level are sorted in descending metric (maximum) value order.<p/>
<a name="preferences"/>
<h2>Preferences</h2>
The metrics preferences allow the display order of the metrics to be changed and the
metrics database to be cleared (to force recalculation of all metrics). In addition, the
toplevel preference page serves as a category for individual metric's preference pages
(category id is net.sourceforge.metrics.ui.MetricsPreferencePage). <p/>

<center>
	<img src="preferences.gif"/>
</center>
<a name="ranges"/>

As of version 1.0.9 of the plugin, the metrics can now trigger warnings that show
up in the task view as well as the editors, indicating methods and types for which metrics
safe ranges are being violated. The minimum and maximum for each metric can be set in the preferences.
This feature is disabled by default, and has to be enabled on the main preference page.<p/>

<center>
	<img src="ranges.gif"/>
</center>

<a name="exportxml"/>
<h2>Export to XML</h2>
Metrics can be exported to an XML file to be processed with XSL into any kind of report
you want. To export metrics, select the scope (project, package, etc.) so it is
displayed in the view. Then use the view's toolbar or dropdown menu to select the export function.<p/>
<center>
	<img src="export.gif"/>
</center>

<a name="colors"/>
<h2>Colors</h2>
The metrics view can use custom colors for the display of metrics. Three colors are used:
<UL>
	<LI>Default color for in-range colors</LI>
	<LI>In-range color for linked metrics (those that can be double-clicked to reveal the source in an editor)</LI>
	<LI>Out-of-range color. These are also double-clickable</LI>
</UL>

<center>
	<img src="colors.gif"/>
</center>


<a name="dependencies"/>
<h2>Dependency Analysis</h2>

Version 1.1.0 and higher include a graphical dependency analyzer. This view is <EM>started
from the metrics view menu or toolbar and it only works when a source folder or entire
project is selected.</EM>
It shows a dynamic hyperbolic graph of the package dependencies, which can be zoomed and rotated.
Use the radio buttons and scrollbar to manipulate the graph. The red and blue
rectangles represent packages, and the edges their dependencies.
Example:<P/>

<center>
	<img src="package_dependencies.gif"/>
</center>

The package dependency graph is analyzed for strong components (all nodes reachable
from each other, called "tangle" from now on) and those nodes are colored red. Other packages not participating in cycles
are colored blue. Right-click on the background of the view to reach the popup menu listing
all the tangles found in the dependency graph. If the menu does not list any, you
are in good shape and your dependency graph has no cycles. 
If you select a cycle, only packages involved in it are shown, as in the following image.<P/>

<center>
	<img src="package_tangle.gif"/>
</center>

The little yellow circle connects all packages involved in the tangle. It shows the number
of nodes involved in the tangle and the longest walk. Right-clicking on the tangle center
(the yellow circular node) shows a pop-up menu with the last entry labeled "Analyze Details".
This option invokes a search using the Eclipse search engine for all types involved in the 
packages of the tangle. The result is a more detailed dependency graph in which the nodes are types,
and the dependencies are between types. The graph only shows dependencies that cross package boundaries.
Every connection in this graph connects two classes in <EM>different packages</EM>. The packages themselves
are green rounded rectangles. Analyzing the detail graph is best done with the hyperbolic slider all the
way to the left, so there is no curvature in the surface. In this mode, type nodes tend to cluster around
their package, but at the same time, they gravitate towards where they are most connected. So if you notice
a very long green connection from a package to a type, but that type is located more closely to some other
package, perhaps it needs to move to that package, apparently being more closely related to the classes
in its vicinity. The next image shows an example of this phenomena.<P/>
<center>
	<img src="tangle_details.gif"/>
</center>
Notice the Metric and Constants types. These seem closely related to the calculators package, yet they
are located in the core package.<P/>

In the construction of these graphs, connections between a package and its types is stronger than the connections
between types. The connections between types involved in a tangle (red) is stronger than regular connections (blue).
Think of the connections as rubber bands with different elasticity.<P/>

In large tangle it is sometimes hard to see why all nodes are connected to each other and how. To help with that,
The tangle popup menu has a "Find Shortest Path" entry that shows the following dialog:<P/>

<center>
	<img src="shortest_path.gif"/>
</center>

<a name="headless"/>
<h1>Headless operation from Ant</h1>
<b>Warning : since version 1.3.6 the anttask.jar as been renamed ant-metricstask.jar</b>
As of version 1.3.2 the metrics plugin contains some ant tasks that can be used for headless
operations as part of a nightly build for example. This section describes how to do this.
<h2>Running eclipse without ui on an Ant build file</h2>
The following example DOS batch file shows how to run a headless build using eclipse, 
edit to match your environment:
<pre>
echo off
setlocal

set JAVA_HOME="c:\program files\jdk141_07" 

set VMARGS="-Xmx256m"

REM The JRE java.exe to be used
set JAVAEXE=%JAVA_HOME%\jre\bin\java.exe"

REM The Eclipse startup.jar
set STARTUPJAR="C:\usr\Eclipse3.1\eclipse\startup.jar"

REM The location of your workspace (does not need to exist)
set WORKSPACE=C:\usr\ecworkspace

if not exist %JAVAEXE% echo ERROR: incorrect java.exe=%JAVAEXE%, edit this file and correct the JAVAEXE envar
if not exist %JAVAEXE% goto done

if not exist %STARTUPJAR% echo ERROR: incorrect startup.jar=%STARTUPJAR%, edit this file and correct the STARTUPJAR envar
if not exist %STARTUPJAR% goto done

:run
@echo on
date /t 
time /t 

%JAVAEXE% %VMARGS% -cp %STARTUPJAR% org.eclipse.core.launcher.Main -noupdate -application org.eclipse.ant.core.antRunner -data %WORKSPACE% -file build.xml %*

date /t 
time /t 

:done
pause
</pre>

Note that the metrics builder determines it is running headless by checking for the
"-noupdate" commandline argument. If it finds there is no UI, it calculates the metrics
in the current (foreground) thread instead of queuing them up and forking a background
thread to perform the calculations.

<h2>Ant tasks provided by this plugin</h2>
<h3>&lt;eclipse.build&gt;</h3>
Convenience task because I did not like the built-in &lt;eclipse.incrementalBuild&gt; task.
Not strictly related to metrics calculation and for a large part copied from an example in an article by 
<em>Barry Searle</em> and <em>Ellen McKay</em> on using Ant with Websphere Studio ApplicationDeveloper.<P/>

	<table border="1">
	<tr><td>parameter</td><td>description</td></tr>
	<tr><td>projectName (String)</td><td>Name of the eclipse project to build</td></tr>
	<tr><td>buildType (String)</td><td>One of "incremental", "full" or "auto"</td></tr>
	<tr><td>failOnError (boolean)</td><td>"true" or "false"</td></tr>
	<tr><td>errorOut (File)</td><td>Compiler errors go here</td></tr>
	<tr><td>errorFormat (String)</td><td>One of "txt" or "xml"</td></tr>
</table>

Example:<P/>
<pre>
	  &lt;eclipse.build 
	  	ProjectName="net.sourceforge.metrics" 
	  	BuildType="full" 
	  	errorOut="errors.xml" 
	  	errorFormat="xml" 
	  	failOnError="true"/&gt;
</pre>
<h3>&lt;metrics.enable&gt;</h3>
Takes only one parameter, <em>projectName</em> and simply enables the metrics for
that project if not already enabled. This adds the metrics nature and build command to the .project file.<P/>
Example:<P/>
<pre>
	  &lt;metrics.enable projectName="net.sourceforge.metrics"/&lt;
</pre>

<h3>&lt;metrics.export&gt;</h3>
<table border="1">
	<tr><td>parameter</td><td>description</td></tr>
	<tr><td>projectName (String)</td><td>Name of the eclipse project to build</td></tr>
	<tr><td>file (File)</td><td>Metrics get exported to this file</td></tr>
</table>

Note that currently only the "metrics-flat-first" export format is supported.<P/>
Example:<P/>
<pre>
	  &lt;metrics.export 
	  	projectName="net.sourceforge.metrics" 
	  	file="metrics-metrics.xml"/&gt;
</pre>

<h2>build.xml example</h2>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;project name="net.sourceforge.metrics" default="build" basedir=".">
	&lt;target name="init">
	   &lt;tstamp/>
	&lt;/target>

	&lt;target name="build" depends="init">
	  &lt;eclipse.refreshLocal resource="net.sourceforge.metrics" depth="infinite"/>
	  &lt;metrics.enable projectName="net.sourceforge.metrics"/>
	  &lt;eclipse.build 
	  	ProjectName="net.sourceforge.metrics" 
	  	BuildType="full" 
	  	errorOut="errors.xml" 
	  	errorFormat="xml" 
	  	failOnError="true"/>
	  &lt;metrics.export 
	  	projectName="net.sourceforge.metrics" 
	  	file="metrics-${DSTAMP}-${TSTAMP}.xml"/>
	&lt;/target>

&lt;/project>
</pre>

<h3>Note</h3>
To my surprise, metrics calculate just fine without the project being built by the java
builder. If your nightly build does not use eclipse to do the compilation, you can still
calculate the metrics using eclipse without incurring a double compilation cycle. 
Simply remove the the java build command from the .project file in the headless project.
Also, only the source folders have to be in the .classpath file since we're not actually compiling
anything, and the metrics builder does not use any jars on the classpath anyways.

<a name="concepts"/>
<h1>Metrics - Meanings</h1>
The following provide brief descriptions of each metric. In these descriptions, the word "scope" refers to the selected element in the
navigator, e.g. a project, source folder, package or compilation unit. I used "Object-Oriented Metrics, measures of Complexity" by Brian Henderson-Sellers, Prentice Hall, 1996
as my primary source of inspiration.<p/>
<center>
	<img src="henderson.jpg"/>
</center>
<h3>Number of Classes</h3>
Total number of classes in the selected scope
<h3>Number of Children</h3>
Total number of <strong>direct</strong> subclasses of a class. 
A class implementing an interface counts as a direct child of that interface
<h3>Number of Interfaces</h3>
Total number of interfaces in the selected scope
<h3>Depth of Inheritance Tree (DIT)</h3>
Distance from class Object in the inheritance hierarchy.
<h3>Number of Overridden Methods (NORM)</h3>
Total number of methods in the selected scope that are overridden from an ancestor class
The calculation of NORM can be customized from its preference page, shown below:<p/>
<center>
	<img src="norm.gif"/>
</center>
Here you can control whether to count abstract methods, methods that call the inherited implementation 
(through use of super.[same-method] call). Certain methods that are supposed to be overridden can be
excluded explicitly (like toString, equals and hashCode).<p/>

<h3>Number of Methods (NOM)</h3>
Total number of methods defined in the selected scope
<h3>Number of Fields</h3>
Total number of fields defined in the selected scope
<h3>Lines of Code</h3>
since version 1.3.6 Lines of code has been changed and separated into:<br>
<ui><li>TLOC: Total lines of code that will counts non-blank and non-comment lines in a compilation unit. usefull for thoses interested in computed KLOC.</li>
<li>MLOC: Method lines of code will counts and sum non-blank and non-comment lines <em>inside</em> method bodies</li>
</ui>
<h3>Specialization Index</h3>
Average of the specialization index, defined as NORM * DIT / NOM. This is a class level metric
<h3>McCabe Cyclomatic Complexity</h3>
Counts the number of flows through a piece of code. Each time a branch occurs (if, for, while, do, case, catch and the ?: ternary operator,
as well as the &amp;&amp; and || conditional logic operators in expressions) this
metric is incremented by one. Calculated for methods only. For a full treatment of this metric see <a href="http://www.mccabe.com/nist/nist_pub.php">McCabe</a>.
<h3>Weighted Methods per Class (WMC)</h3>
Sum of the McCabe Cyclomatic Complexity for all methods in a class
<h3>Lack of Cohesion of Methods (LCOM*)</h3>
A measure for the Cohesiveness of a class. Calculated with the Henderson-Sellers method (LCOM*, see page 147).
If (m(A) is the number of methods accessing an attribute A, calculate the average of m(A) for all attributes, subtract 
the number of methods m and divide the result by (1-m). A low value indicates a cohesive class and a value close to 1
indicates a lack of cohesion and suggests the class might better be split into a number of (sub)classes.<P/>
I'm unsure of the usefullness of this metric in Java since it penalizes the proper use of getters and setters as the only methods
that directly access  an attribute and the other methods using the gettter/setter methods. Perhaps I could alter the implementation
to take this into account, assuming standard JavaBean naming conventions.<p/>

The LCOM* metric has it's own preference page, shown below:<p/>

<center>
	<img src="lcom.gif"/>
</center>
Here you can control whether static fields and static methods should be considered in the calculation of LCOM*.<p/>

<h2>Robert C. Martin Suite</h2>
The following are the coupling metrics as defined by Robert Martin in 
<a href="http://www.objectmentor.com/resources/articles/oodmetrc.pdf">"OO Design Quality Metrics,
An Analysis of Dependencies"</a>, and more recently in his book named "Agile Software Development,
Principles, Patterns and Practices".

<center>
	<img src="martin.jpg"/>
</center>

<h3>Afferent Coupling (Ca)</h3>
The number of classes outside a package that depend on classes inside the package.
<h3>Efferent Coupling (Ce)</h3>
The number of classes inside a package that depend on classes outside the package.
<h3>Instability (I)</h3>
Ce / (Ca + Ce)
<h3>Abstractness (A)</h3>
The number of abstract classes (and interfaces) divided by the total number of types in a package
<h3>Normalized Distance from Main Sequence (Dn</h3>
| A + I - 1 |, this number should be small, close to zero for good packaging design.

<a name="license"/>
<h1>Licenses and Credits</h1>
The metrics plugin is CPL1.0, the same license as Eclipse itself. 
It uses the following open source code by others, without these packages, this tool would not have
been possible. Thanks for all the good work! The source to any modifications is available in the metricssrc.zip.<P/>
<h3>JDBM</h3>
I use the JDBM package as the persistence layer for the metrics. Very cool package! 
I use the HTree (persistent hashtable) with a MRU Cache of size 500.
JDBM carries the BSD license and can be obtained from <a href="http://jdbm.sourceforge.net">jdbm.sourceforge.net</a>.
<h3>Touchgraph</h3>
The (AWT) graphing tool used for the dependency graphs. Made some minor modifications to add popup
menu entries and embedd it in Eclipse. Touch graph was developed by Alexander Shapiro, and is LGPL.
Visit <a href="http://www.touchgraph.com">http://www.touchgraph.com</a> for more cool examples and 
more details.

<h3>Classycle</h3>
The detection of the tangles (strong components) in the dependency graph is based on code by
Franz-Josef Elmer, classycle v 0.9, which implements Tarjan's algorithm. This code is distributed under a BSD
like license. See <a href="http://sourceforge.net/projects/classycle">http://sourceforge.net/projects/classycle</a>
for details and updates.
</body>
</html>